Glossary Class Reference

Detailed Description

This class is used for reading configuration files:

• Reads a std::istream to builds a std::map of <key, record>
• Simple syntax based on = ( ) { } “ , ; % focused on flexible value setting.
• each record is a list of values
• Provides values upon requests with function set(key, index) .
• A counter records the usage of the values.

Notes:

1. There can be an arbitrary number of Keys, and an abitrary number of values for each key.
2. Values are kept as strings, and are converted at request by templated functions:

   template <typename T> int set(T & ptr, std::string key)

   • key is the name under which the value appeared,
   • The template argument T defines the type of the parameter, and the value-string is interpreted accordingly,
   • The interpreted value is stored in ptr,
   • Returns 1 if ptr was set successfully, 0 otherwise
3. The method warning() can report values that have not been used, or that have been used more than once.

Class reviewed by Andre Clapson on 10.03.2011.

Todo:

parse and instantiate values like 'random.uniform()' or 'PI*30' or '0.1/60'

Classes
struct	val_type
	a string-encoded value with a counter More...

Public Types
typedef std::string	key_type
	type for a key
typedef std::vector< val_type >	rec_type
	a record is a set of values associated with a key
typedef std::map< key_type, rec_type >	map_type
	type for the list of (key, record)
typedef std::pair< key_type, rec_type >	pair_type
	type of a pair (key, record)

Public Member Functions
	Glossary ()
	initialize
	Glossary (std::istream &in)
	this constructor calls read(in)
	Glossary (const std::string &)
	this constructor calls read()
bool	empty () const
	true if no key were set
unsigned	nb_keys () const
	number of keys
bool	has_key (key_type const &)
	return true if key is present, even if no value was set
bool	use_key (key_type const &)
	return true if key is present; the key is deleted
void	erase (key_type const &)
	remove given key
void	clear ()
	clear all entries
Glossary	extract (key_type const &)
	create a new Glossary with only the given key
unsigned	nb_values (key_type const &)
	return number of values associated with a key
rec_type *	values (key_type const &)
	gives a pointer to the values corresponding to a key, or null if the key is not present
rec_type const *	values (key_type const &) const
	gives a const pointer to the values corresponding to a key, or null if the key is not present
std::string	value (key_type const &, unsigned indx)
	return the value corresponding to the key and the index, or the empty string
int	warnings (std::ostream &, unsigned threshold=1) const
	report unused values and values used multiple times More...
void	set_values (key_type const &, const std::string &rhs, int no_overwrite=2)
	this is equivalent to read('k = rhs') More...
void	read (std::istream &, int no_overwrite=2)
	update the glossary to include assignments stored in a stream More...
void	read (const std::string &, int no_overwrite=2)
	update the glossary to include assignments stored in a string
void	readFile (const char path[], int no_overwrite=2)
	read file specified in path
void	readStrings (int argc, char *argv[], int no_overwrite=2)
	a read for C-style command-line arguments More...
void	write (std::ostream &) const
	write all [key, values]
template<typename T >
int	set (T &var, key_type const &key, unsigned inx=0)
	set var from key[inx]. The counter associated to the value is incremented.
template<typename T >
int	query (T &var, key_type const &key, unsigned inx=0) const
	set var from key[inx]. The counter is not changed
template<typename T >
int	set (T *ptr, unsigned cnt, key_type const &key)
	set cnt values in the array ptr[], starting at key[0]
template<typename T >
int	set (T &var, key_type const &key, KeyList< T > const &dict, unsigned inx=0)
	set var from key[inx], using the dictionary dict
template<typename T >
void	set_value (key_type const &key, const T &var, int no_overwrite=2)
	set the first value of the key: key[0]=var.
int	is_alpha (key_type const &key, unsigned inx=0) const
	check if value associated with key at index inx is made only of alpha characters
template<>
void	set_one (std::string &var, std::string const &val, key_type const &key) const
	special function for std::string arguments. More...
template<>
void	set_one (float &var, std::string const &val, key_type const &key) const
	special function for float More...
template<>
void	set_one (double &var, std::string const &val, key_type const &key) const
	special function for double More...

Static Public Member Functions
static int	warnings (std::ostream &, pair_type const &, unsigned threshold=1)
	report unused values and values used more than threshold times More...
static void	write (std::ostream &, pair_type const &)
	write [ key = value1, value2, ... ]
static void	write_cnt (std::ostream &, pair_type const &)
	write the number of time each value has been used More...

Member Function Documentation

void read	(	std::istream &	is,
		int	no_overwrite = 2
	)

If no_overwrite == 0, a setting can erase a previous value, If no_overwrite == 1, symbols that are already present are not over-written, If no_overwrite == 2, a exception is thrown for any duplicate symbol

void readStrings	(	int	argc,
		char *	argv[],
		int	no_overwrite = 2
	)

This is useful to parse the command-line strings given to main().

The following syntax will be accepted: FILE.EXT and recorded as: EXT = FILE.EXT

void set_one	(	std::string &	var,
		std::string const &	val,
		key_type const &	key
	)		const

This copies the string, removing spaces

void set_one	(	float &	var,
		std::string const &	val,
		key_type const &	key
	)		const

This reads a floating point value, also accepting 'inf', '+inf' and '-inf'

void set_one	(	double &	var,
		std::string const &	val,
		key_type const &	key
	)		const

This reads a floating point value, also accepting 'inf', '+inf' and '-inf'

void set_values	(	key_type const &	k,
		const std::string &	rhs,
		int	no_overwrite = 2
	)

This should be equivalent to read('k = rhs')

int warnings ( std::ostream &  os, Glossary::pair_type const &  pair, unsigned  threshold = 1  )

static

Returns

:

• 1 if something suspicious was detected, and a warning was issued,
• 0 otherwise

Todo:

: use color only if the terminal supports it

int warnings	(	std::ostream &	os,
		unsigned	threshold = 1
	)		const

Returns

the number of warnings that were issued

void write_cnt ( std::ostream &  os, Glossary::pair_type const &  pair  )

static

Write the usage-counter for each value. The width of each record will match what is printed by Glossary::write()